Skip to content

feat: a static service forwards paths to another server (ADR-0110) - #552

Merged
7schmiede merged 2 commits into
mainfrom
feat/static-forward
Nov 17, 2026
Merged

7schmiede merged 2 commits into
mainfrom
feat/static-forward

Conversation

@7schmiede

Copy link
Copy Markdown
Member

What and why

A profile that turns a dev server into kind = "static" lost the dev server's proxy config: a single-page app calling its API on its own origin (relative /api) got index.html or a 404, and a separate reverse-proxy stack was the only way out. A static service now forwards path prefixes to another server:

[profiles.acceptance.services.web]
kind    = "static"
build   = "npm run build -- --configuration e2e"
output  = "web/dist/web"
forward = { "/api" = "{service.api.url}", "/file" = "{service.api.url}", "/otel" = "{compose.app.otel-collector.4318}" }
  • crates/devstack-config: the key on a service and a profile's service, the shared rules in forward.rs, the checks (prefix form, target an http:// origin with env's placeholders, a service with insecure_tls and a skipped container refused), FORWARD_SINCE = "0.49.0" and its warning.
  • devstack serve-static --forward PREFIX=URL; the daemon appends one per entry to the static service's generated run, so placeholders resolve per lane.
  • staticsrv::pass: reverse proxy per request (Host kept, X-Forwarded-For/-Host/-Proto, hop-by-hop headers stripped both ways, streamed answers, WebSocket upgrades joined, 502 naming the target).
  • Docs: docs/stack-file.md, skill devstack-config, ADR-0110.

Closes #551

Review card

Approved by the owner in the conversation on 2026-11-17, points 1–6.

# Category Point Beats Reversing costs
1 contract A new optional key forward maps a path prefix to a target; only for kind = "static", also in [profiles.<p>.services.<s>]; elsewhere a check error; FORWARD_SINCE with its warning. A proxy service per repository (Caddy, Node); an absolute API URL plus CORS A published key goes only as a deprecated alias (ADR-0023)
2 concept The longest prefix wins, at a segment boundary only (/api takes /api, /api/…, /api?…, not /apix); path and query unchanged; a forwarded path never falls back to a file or index.html. A plain string prefix Low while no one uses it
3 contract A target is an origin http://host:port, no path, no https; env's placeholders, resolved when the instance starts; check refuses a path, insecure_tls and a skipped container. strip/path rewrite and TLS to the target now Loosening later is compatible
4 trust As a reverse proxy: Host kept, X-Forwarded-* added, hop-by-hop headers on their hop, streamed answers, WebSocket upgrades pass (as ADR-0010's proxy). Rewriting Host to the target A header change targets checking Host notice
5 concept An unreachable target is a 502 at once, naming it; the health check stays on the files. Holding requests until the target is ready Adding holding later is compatible
6 trust Forwards are reachable wherever the static port is, a public link (devstack tunnel) included, as in production behind a reverse proxy. Limiting the tunnel to the files Switching forwards off in the tunnel is a visible change

Decided while building: the forward runs in the static service's own process; one connection per request, no pool; a target without a port is port 80; prefixes take letters, digits and -._~ only.

Verified

  • cargo fmt, cargo clippy --workspace --all-targets -D warnings, cargo test --workspace on Windows.
  • Unit tests against a real upstream: path and query unchanged, Host and X-Forwarded-*, an SSE event arriving while its stream stays open, a WebSocket echo, a 502 for a closed port, /apix served by the app.
  • Integration (DEVSTACK_INTEGRATION=1, lifecycle_services_only): the daemon's static site answers /info from the .NET API through its forward.
  • Not verified locally: Linux and macOS (CI).

🤖 Generated with Claude Code

7schmiede and others added 2 commits November 17, 2026 17:55
A `kind = "static"` service takes `forward = { "/api" = "{service.api.url}" }`,
also in a profile: requests below a prefix go to the target as a reverse
proxy in front of the bundle would send them, so a single-page app that
calls its API on its own origin runs as a static build without a proxy of
its own. The longest prefix wins at a segment boundary; the path goes on
unchanged; Host is kept, X-Forwarded-* added; answers stream, WebSocket
upgrades pass; an unreachable target is a 502. `devstack check` checks
prefixes and targets (an origin over plain HTTP, a skipped container) and
warns below `requires = "0.49.0"`.

Closes #551

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@7schmiede
7schmiede merged commit 298e107 into main Nov 17, 2026
14 checks passed
@7schmiede
7schmiede deleted the feat/static-forward branch November 17, 2026 17:07
@7schmiede 7schmiede mentioned this pull request Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Static service: forward paths to another service (same-origin API for a static SPA in a profile)

1 participant